"""
PlumeSoft 量化代码库
作者：PlumeSoft
用途：为 optuna 设计的支持多进程、不依赖数据库、支持持久化保存的高性能炼丹基础框架
"""

import pandas as pd
from optuna import Trial


class Base_Bayesian(object):
    """
    用于实现贝叶斯具体业务的基础类，具有实际功能的贝叶斯炼丹炉需要继承该类并实现类中的业务函数。
    注意：
        1. 该类中的函数都是可重写的，但不要修改函数名，否则框架无法识别。
    """

    def prepare_global_data(self, params: dict) -> dict:
        """
        准备全局数据，可以在这里进行读取数据、合并数据等数据预处理操作。
        全局数据在主任务中执行一次，被所有后台子任务共享。
        在这个函数中可以使用多任务处理，因为这个函数只在主任务执行。

        Args:
            params (dict): 用来传入和返回公共数据
        Returns:
            dict: 返回修改后的 params 字典
        """
        return params

    def prepare_task_data(self, params: dict) -> dict:
        """
        准备任务用到的数据，可以在这里执行数据读取、初始化等操作。
        这个函数只在每个后台任务启动时执行一次。
        注意：尽量不要在这个函数中使用多任务处理，因为框架本身已经是多任务的了。

        Args:
            params (dict): 用来传入和返回公共数据
        Returns:
            dict: 返回修改后的 params 字典
        """
        return params

    def execute_trial(
        self, trial: Trial, params: dict, result_queue, score_queue
    ) -> float:
        """
        炼丹迭代任务回测主函数。
        这个函数会执行多次，每次生成新的参数，进行回测，返回评分值。
        注意：尽量不要在这个函数中使用多任务处理，因为框架本身已经是多任务的了。

        Args:
            trial (Trial): 测试对象，用于生成炼丹参数
            params (dict): 用于炼丹的配置和公共参数，包含由 prepare_data 提供的数据
            result_queue (queue): 用于向主任务返回单次测试的结果，DataFrame 格式，其中需要包含 score 评分字段
            score_queue (queue): 用于向主任务返回高分数据和参数，包含4个变量

        Returns:
            float: Optuna 要求的评分值，越高表示测试结果越好
        """
        # 返回评分值，用于训练任务评估训练结果和方向，分数越大越好
        return -1

    def study_finished(
        self, params: dict, result_df: pd.DataFrame, study_df: pd.DataFrame
    ):
        """
        炼丹完成回调函数。

        Args:
            params (dict): 用于炼丹的配置和公共参数，包含由 prepare_data 提供的数据
            result_df (pd.DataFrame): 包含所有迭代执行结果的数据集
            study_df (pd.DataFrame): 由 Optuna 生成的学习结果数据集
        """
        pass
